feat(runtime): add flow-aware execution runtime by chhoumann · Pull Request #1173 · chhoumann/quickadd

chhoumann · 2026-04-25T19:45:32Z

Add a shared flow-aware execution runtime across QuickAdd engines and isolate Templater integration behind an explicit capability boundary.

This introduces runtime execution context/result/diagnostic/artifact models, threads shared flow state through macro/capture/template execution, and moves Templater probing into src/integrations/* instead of scattering duck-typed checks through engine code. It also includes the follow-up fixes from review validation: non-interactive CLI runs now use whole-flow preflight, CLI/API callers honor ChoiceExecutionResult failure states, and Templater diagnostics are gated to meaningful cases.

This work was done because the existing execution model treated too much behavior as isolated string transforms, which made nested flow execution hard to reason about and made Templater integration brittle. The follow-up fixes make the new runtime safer at the boundaries without changing persisted choice schemas.

Focus review on src/engine/runtime/*, src/integrations/*, src/choiceExecutor.ts, the engine/runtime callers, and the CLI/preflight/API boundary changes. No persisted schema migration is included.

Summary by CodeRabbit

New Features
- CLI check/run returns richer structured diagnostics (missing inputs/flags, diagnosticCount, flow.choice metadata) and explicit run outcomes (success/aborted/failed).
- Macros and nested choices run in one shared flow context with preserved variable scoping and immediate abort propagation.
- Improved capture/template behavior and Templater handling (suppression on-create, trigger waiting, cursor jump, diagnostics).
Documentation
- Updated docs for flow-aware CLI validation, diagnostics, capture/template semantics, and integration details.

vercel · 2026-04-25T19:45:35Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
quickadd	Ready	Preview	Apr 26, 2026 4:15pm

coderabbitai · 2026-04-25T19:45:38Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Introduces a runtime ChoiceExecutionContext and structured ChoiceExecutionResult/CommandExecutionResult models; adds flow-aware preflight traversal (collectChoiceFlowPreflight) that reports diagnostics and flow.choice metadata; centralizes Templater integration via IntegrationRegistry and FormatOrchestrator; threads execution context through executors, engines, and formatters; surfaces diagnostics and structured results in CLI handlers.

Changes

Cohort / File(s)	Summary
Documentation `docs/docs/Advanced/CLI.md`, `docs/docs/Advanced/onePageInputs.md`, `docs/docs/Choices/MacroChoice.md`, `docs/docs/Choices/CaptureChoice.md`, `docs/docs/QuickAddAPI.md`	Document flow-aware CLI preflight, new CLI JSON fields (`diagnostics`, `flow.choices`, `missingFlags`), nested-choice scoping, capture/macro semantics, and executeChoice variable snapshotting.
Runtime models `src/engine/runtime/artifact.ts`, `src/engine/runtime/context.ts`, `src/engine/runtime/diagnostic.ts`, `src/engine/runtime/result.ts`, `src/engine/runtime/index.ts`	Add ChoiceExecutionContext, artifact/diagnostic/result models and factories; provide context step IDs, artifact creation, diagnostic shape, and barrel exports.
Preflight traversal `src/preflight/collectChoiceFlowPreflight.ts`, `src/preflight/collectChoiceFlowPreflight.test.ts`	New traversal that walks nested choices (macros/conditionals), collects/deduplicates requirements, computes unresolved inputs, emits templater/integration diagnostics, and returns flattened choice summaries (path/depth).
CLI & handlers `src/cli/registerQuickAddCliHandlers.ts`, `src/cli/registerQuickAddCliHandlers.test.ts`	Switch run/check to use collectChoiceFlowPreflight; include diagnostics/flow metadata and diagnosticCount/choiceCount in responses; handle structured ChoiceExecutionResult statuses (`success`/`aborted`/`failed`) and serialize diagnostics.
Choice execution core `src/IChoiceExecutor.ts`, `src/choiceExecutor.ts`, `src/choiceExecutor.runtime.test.ts`	IChoiceExecutor.execute now returns `ChoiceExecutionResult`; ChoiceExecutor creates/reuses ChoiceExecutionContext, tracks executionDepth, returns standardized results (`success`/`skipped`/`aborted`/`failed`), exposes getExecutionContext, and tests updated for result/abort semantics.
Engines & formatters `src/engine/QuickAddEngine.ts`, `src/engine/TemplateEngine.ts`, `src/engine/TemplateChoiceEngine.ts`, `src/engine/SingleTemplateEngine.ts`, `src/engine/CaptureChoiceEngine.ts`, `src/formatters/completeFormatter.ts`, `src/formatters/captureChoiceFormatter.ts`	Thread ChoiceExecutionContext into engines/formatters; update constructors and run contracts; delegate templater operations to FormatOrchestrator; derive originLeaf from context; record artifacts/diagnostics into context.
Format orchestration `src/engine/runtime/FormatOrchestrator.ts`, `src/engine/runtime/FormatOrchestrator.test.ts`	New FormatOrchestrator centralizes templater integration calls, emits capability diagnostics when integrations/capabilities are missing, provides parse/overwrite/wait/jump helpers, and records capture plans/results as artifacts.
Templater integrations & registry `src/integrations/TemplaterIntegration.ts`, `src/integrations/TemplaterIntegration.test.ts`, `src/integrations/IntegrationRegistry.ts`, `src/integrations/index.ts`	Add TemplaterIntegration interface with Noop/Obsidian implementations, capability reporting, overwrite/wait/jump/suppression behavior; add per-App IntegrationRegistry and accessors; tests included.
Macro engine updates `src/engine/MacroChoiceEngine.ts`, `src/engine/MacroChoiceEngine.entry.test.ts`, `src/engine/MacroChoiceEngine.notice.test.ts`	Macro run now returns ChoiceExecutionResult, records per-command CommandExecutionResult array, centralizes child-abort handling using returned ChoiceExecutionResult, and exposes getCommandResults(); tests updated for typed results and abort semantics.
API & utilities `src/quickAddApi.ts`, `src/quickAddApi.executeChoice.test.ts`, `src/utilityObsidian.ts`, `src/utilityObsidian.templater-binding.test.ts`	executeChoice snapshots/restores executor variables and validates child ChoiceExecutionResult (throws on aborted/failed); templater helpers delegate to IntegrationRegistry.templater; tests updated to integration-backed behavior.
Plugin wiring `src/main.ts`	QuickAdd plugin gains an `integrations` field and registers an IntegrationRegistry on plugin load.
Misc. tests & startup `src/engine/StartupMacroEngine.ts`, `src/engine/StartupMacroEngine.test.ts`, `src/engine/.../*.test.ts`	Added/updated tests covering choice execution results, diagnostics/artifacts propagation, templater capability diagnostics, abort propagation, and startup macro abort handling.

Sequence Diagram(s)

sequenceDiagram
    participant CLI as CLI Handler
    participant Preflight as collectChoiceFlowPreflight
    participant Executor as ChoiceExecutor
    participant Engine as ChoiceEngine
    participant Orchestrator as FormatOrchestrator
    participant Templater as TemplaterIntegration

    CLI->>Preflight: collectChoiceFlowPreflight(choice)
    Preflight->>Preflight: traverse choices, collect requirements & diagnostics
    Preflight->>Templater: inspect templates / check capabilities
    Preflight-->>CLI: ChoiceFlowPreflightResult { requirements, unresolvedRequirements, diagnostics, choices }

    CLI->>Executor: execute(choice)
    Executor->>Executor: create/reuse ChoiceExecutionContext
    Executor->>Engine: run(choice, executionContext)
    Engine->>Orchestrator: parse/overwrite/wait/jump as needed
    Orchestrator->>Templater: parseTemplate / overwriteFileOnce / wait / jump
    Templater-->>Orchestrator: capability/result
    Engine-->>Executor: ChoiceExecutionResult { status, artifacts, diagnostics, error? }
    Executor-->>CLI: mapped CLI response (ok/aborted/failed + diagnostics/flow)

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

feat(cli): add native QuickAdd Obsidian CLI handlers #1129 — Related: CLI handler and preflight changes integrating flow-aware preflight and structured CLI responses.
Templater: deterministic snippet rendering (capture + template append) #1017 — Related: Templater/file-creation behavior and integration centralization overlapping with IntegrationRegistry/FormatOrchestrator work.
fix: stop macros and APIs immediately when cancellations occur #976 — Related: Abort signaling and propagation through executor/engine; overlaps with result/status handling.

Suggested labels

released

Poem

🐰 I hop through contexts, variables tucked tight,

Preflight maps choices by path and depth tonight,
Templater hums under orchestrated light,
Diagnostics bloom and results take flight,
A rabbit cheers — the flow feels right!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 1.75% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat(runtime): add flow-aware execution runtime' directly and concisely summarizes the main change: introducing a shared, flow-aware execution runtime across QuickAdd engines.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/flow-runtime-review-fixes

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

cloudflare-workers-and-pages · 2026-04-25T19:47:03Z

Deploying quickadd with Cloudflare Pages

Latest commit:	`a5d5cfc`
Status:	✅ Deploy successful!
Preview URL:	https://02a3f5fc.quickadd.pages.dev
Branch Preview URL:	https://codex-flow-runtime-review-fi.quickadd.pages.dev

View logs

devin-ai-integration

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 7 additional findings.

vercel Bot deployed to Preview April 25, 2026 19:45 View deployment

chhoumann marked this pull request as ready for review April 25, 2026 19:51

chhoumann added 2 commits April 25, 2026 21:52

feat: add flow-aware execution runtime

a887cf2

fix: validate flow runtime review findings

7dec0eb

chhoumann force-pushed the codex/flow-runtime-review-fixes branch from daef0eb to 7dec0eb Compare April 25, 2026 19:53

chhoumann changed the title ~~fix(runtime): validate flow runtime review findings~~ feat(runtime): add flow-aware execution runtime Apr 25, 2026

chhoumann changed the base branch from codex/flow-runtime-review to master April 25, 2026 19:53

chhoumann marked this pull request as draft April 25, 2026 19:53

vercel Bot deployed to Preview April 25, 2026 19:53 View deployment

chhoumann marked this pull request as ready for review April 25, 2026 19:55

devin-ai-integration Bot reviewed Apr 25, 2026

View reviewed changes